fix(mcp,runtime): describe_object serves readonly: true where a write never sets the value - #33150

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/mcp, @objectstack/runtime, touching 5 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/authorization.mdx (via buildMcpBridge (symbol, a top-level function))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c272bbaa8ae3e62e1df8bf4ee630c9972c6d97f2 && git checkout c272bbaa8ae3e62e1df8bf4ee630c9972c6d97f2
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 128b6571f476d4fae347d8f860b04b95927d2cce 92fba691f927d91ef8ac9103042b8ef7236de7b0 && git checkout -B drift-repro 128b6571f476d4fae347d8f860b04b95927d2cce && git merge --no-ff 92fba691f927d91ef8ac9103042b8ef7236de7b0

node scripts/docs-audit/affected-docs.mjs --json 128b6571f476d4fae347d8f860b04b95927d2cce

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 128b6571f476d4fae347d8f860b04b95927d2cce → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#7 · os-tesla · session_01L9qibzuZJBQY4wUQFJbkfx

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 819ea267b98ed14fd84c2055446301bd082ddf61
Local-runs: none

① Derived judgments

• Runtime-owned arm: right. RUNTIME_OWNED_FIELD_TYPES (spec/data/field.zod.ts, {autonumber}) is the set objectql strips on both verbs: insert stripRuntimeOwnedFields, update stripReadonlyFields through isRuntimeOwnedField (objectql/validation/rule-validator.ts). The only exemptions are isSystem and create-side preserveAudit, and MCP passes neither (no preserveAudit in packages/mcp/src or runtime/src/domains/mcp.ts). So create versus update agree, and a flagless literal is now true.
• Formula arm: right. isVirtualSearchField is SEARCH_VIRTUAL_TYPES = {formula} (spec/data/search-fields.ts). That is the same key stripComputedWriteFields (objectql/engine-top-level.ts) strips on, in every context, on insert, update and validate.
• Stored-expression arm: right. Boolean(f.expression) equals planStoredExpressions's def.type !== 'formula' && def.expression, and formula is already true by then. The engine overwrites the value in every case: insert computeStoredExpressions then Object.assign; by-id update applyStoredExpressionsToPatch overwrites a key the caller sent; predicate update settleBulkStoredExpressions deletes the caller's key. Nothing only defaults it.
• No false true found. summary stays false (the engine persists a value the caller sends). readonlyWhen is untouched. System columns already carried the declared flag. A plain field stays false. An FLS edit-deny stays false by design (item 2b).
• Twins: agree by copy, not by construction. Each twin has its own writeNeverSetsField over the same two spec imports, plus a local expression test that mirrors objectql. No local type list. They differ only in the guard (typeof f !== 'object' in runtime), which is harmless.
• S1 (should-fix): the stored-expression arm misses for a field-projected caller. mcp-server-runtime.ts:writeNeverSetsField / runtime/domains/mcp.ts:writeNeverSetsField read the masked definition (callerObjectView → applyObjectSchemaMask; maskObjectSchema). metadata-core/object-schema-fls-references.ts FIELD_REFERENCE_POSITIONS.expression deletes a readable field's expression when it mentions a field the caller is denied. That caller is served doubled as readonly: false while the engine still overwrites the value. Nothing serves a wrong true (no regression; the field shows the pre-PR answer), but the changeset's "for a stored field that declares an expression" is not true for that caller, and no pin covers it. Fix one of two ways: compute the verdict from the definition before the mask (it reveals only "computed", not the inputs), or narrow the changeset and JSDoc sentence and record the gap as a follow-up.
• N1 (nit): the formula predicate is named for search. It is the right set today, and a write-named spec predicate would be a spec change of its own (the dev flags this).

② Semver level

• patch for @objectstack/mcp and @objectstack/runtime is right. The diff publishes only these two. Metadata-protocol: none is right: no authorable key, value or default changes. Clause-②: yes (widening) is right: an existing answer reads true more often and no input is newly refused. Both lines open a line in the PR body and in the changeset body (AGENTS.md Post-Task Checklist 3). This is not BREAKING.
• No Skills-docs: line is owed. packages/mcp/src/skill-md.ts, ui/apps/console/src/pages/developer/objectstack-skill.ts and skills/objectstack-ai/SKILL.md name describe_object but restate neither readonly nor defaultValue.
• N2 (nit): the stale sentence item 3 removes ("describe_object serves what it served before") survives in packages/mcp/src/mcp-validate-expression.option-labels.test.ts (header JSDoc). It is test prose and outside the card's named site.

③ Boundary flags

• Item 2 (b): true. resolveObjectSchemaMaskPosture (metadata-core/object-schema-fls.ts) asks only getMetadataReadableFields/getReadableFields and canReadObject, and the posture carries readable only. The edit verdict is ISecurityService.getWritableFields (spec/contracts/security-service.ts), a separate read. The description sentence ("shows readonly false, and a write naming it is refused") is true: plugin-security's FLS write step (security-plugin-authz-middleware.ts 2.5) answers 403 and does not strip. The runtime pin measures PERMISSION_DENIED/403.
• Expression arm scope: within the card's class. It is the same defect (value served writable, engine replaces it) on the same function, and the spec's expression contract says "a client-sent value never stands". It needs no card of its own. S1 is its only gap.
• defaultValue sentence: true. Both twins serve f.defaultValue raw, and FieldSchema.defaultValue admits a CEL envelope or the NOW()/current_user tokens, applied on INSERT when the field is omitted or null. The rewritten optionFieldsOf JSDoc (mcp-http-tools.ts) is true: describe_object serves options under the same declaresOptions.
• Pins and CONTROL: real. Runtime [#32530]: title/qty false and frozen_note true, beside the four computed fields true, over the real ObjectQL, SqlDriver and SecurityPlugin. The engine leg measures each sent value dropped or replaced. Stdio [#32530] covers the tool and buildObjectSchemaResource, and DECLARED_ANSWER's bonus_formula flips. The dev reports red without the change (1 runtime, 4 stdio) and red on each arm's ablation, CONTROL included; I did not re-run them. N3 (nit): the engine leg is create-only. Update rests on the engine code read above.
• Gates (check-runs at head, 48): 14 success, 16 skipped, 18 in_progress (Build Core, Test Core 1–8/8, Type Check workspace/debt ledger/consumer gates, five Lint jobs), 0 failure. Merge waits on those.

Implemented-by: claude/project-thread-6xoa43
Reviewed-by: session_01L9qibzuZJBQY4wUQFJbkfx

VERDICT: PASS

domain:server#7 · os-tesla · session_01L9qibzuZJBQY4wUQFJbkfx

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 92fba691f927d91ef8ac9103042b8ef7236de7b0
Local-runs: none

① Derived judgments

The delta from 819ea267 is made of fix 56546bd5, changeset 48fff48a, and the merge 92fba691 (#33144, #33121, #33129). The net diff against main is still the PR's 7 files. d05eae15, named as the fix, is the blob of runtime/src/domains/mcp.ts at 48fff48a, not a commit.

• S1 (R1 should-fix): fixed on HTTP. runtime/domains/mcp.ts buildMcpBridge.describeObject now inlines readObjectForCaller's two steps: readServedObject, then servedToCaller. It passes the declaration to describeServedObject(def, declared), which reads writeNeverSetsField(declared?.fields?.[k]) and nothing else from it. The keys still come from the masked def.fields, so a denied field gets no entry.
• No new read. readServedObject is the same call readObjectForCaller made, and servedToCaller keeps the same per-request masker. The caller could already cause every read.
• No other key leaks. name, label, type, required, system, options, defaultValue, validations and enableFeatures are all still read from def. The only fact the declaration adds is one boolean: "this readable field is computed". The expression and its inputs stay hidden. The mask (projectMetaObjectSchema → applyObjectSchemaMask, which is pure) never adds or deletes readonly (FIELD_REFERENCE_POSITIONS.readonly: keep), and it never changes type. Audit-field governance runs before the mask, in the protocol read (protocol-meta-type-schema.ts). So declared and def differ, for the predicate, only on expression. No other arm can move.
• Twins: they now differ on purpose. The mcp twin's JSDoc (mcp-server-runtime.ts:writeNeverSetsField ⚠️) states the gap and points to the HTTP twin. The stdio bridge (stdio-data-bridge.ts → describeServedObject(def)) and the resource (buildObjectSchemaResource) are unchanged and read only the masked view (plugin.ts callerObjectView, or the bare view when there is no principal). The gap is filed as mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156 (open).

② Semver level

• No change from round 1. patch for @objectstack/mcp and @objectstack/runtime. Clause-②: yes (widening) and Metadata-protocol: none still open lines in the changeset body. No Skills-docs: line is owed.
• The stdio wording is exact. The changeset says "Over stdio and on the resource, which hold only the object as the caller is served it, the expression case answers true where the caller is shown the expression". With a principal that is the masked view; without one, the caller is served the bare view. Both are covered. The HTTP sentence ("judged on the field as declared … the expression itself stays hidden") matches the code.
• N2 (R1 nit): fixed. mcp-validate-expression.option-labels.test.ts header.

③ Boundary flags

• The new pin fails without the fix (by reading; not re-run). [#32530] … a stored expression over a field the caller cannot read sets marked_up (record.hidden_cost * 2) and denies the member read on hidden_cost.
  • Under the R1 code the masked marked_up is {type:'number'} with no flag and no expression, so it is served false, and toBe(true) goes red.
  • The precondition proves the mask deletes the expression (through the /meta door, the same projectMetaObjectSchema) and that the declaration keeps it. That rules out a vacuous green.
  • The leak checks (hidden_cost absent, no record. in the answer) are real. record. would pass even before the fix, because describe_object never serves expression.
  • The R1 CONTROL and the item-2 pins are unchanged.
• The merge does not interact. fix(runtime): MCP list_actions marks a confirmation-gated action unavailable for an AI service account #33144 touches list_actions (actionConfirmationRefusal) and the McpActionSummary.unavailable JSDoc only. No hunk reaches describeServedObject, writeNeverSetsField or the describe_object description.
• N1 (R1 nit): open, unchanged. The formula predicate's name is about search.
• N3 (R1 nit): open, unchanged. The engine leg is create-only.
• N4 (new, nit): the PR body was not updated for round 2.
  • "Item 1, both twins … serve readonly from writeNeverSetsField(f)" is no longer true of the HTTP twin.
  • Tests and Verification name neither the new pin nor mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156.
  • The changeset carries the correct text, so this is prose only.
• Tool description: the shared describe_object sentence lists "a field with an expression" as readonly. Over stdio, a masked caller can see false for such a field. That is the mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156 gap and is not a new finding.
• Gates (check-runs at 92fba691, 51): 35 success, 16 skipped, 0 in progress, 0 failure. Build Core, Test Core 1–8/8, all Type Check and Lint jobs, Check Changeset and the Governed Surface Queue Guard are all green.

Implemented-by: claude/project-thread-6xoa43
Reviewed-by: session_01L9qibzuZJBQY4wUQFJbkfx

VERDICT: PASS

domain:server#7 · os-tesla · session_01L9qibzuZJBQY4wUQFJbkfx

维护者速读 · PR #33150 @ 92fba691 · 2026-11-13T22:48Z

• 改了什么：MCP describe_object（HTTP 与 stdio）和 objectstack://objects/{name} 资源，对「写了也不会生效」的字段回答 readonly: true：自动编号、公式字段、声明了 expression 的存储计算字段。工具说明写明 readonly 是 schema 的判断，不是调用者的编辑权限；defaultValue 可能是服务端令牌或表达式对象，代理应省略而不是照抄。
• 为什么改：以前只看字段上声明的 readonly 标记，代理以为这些字段可写，写进去被引擎丢弃或覆盖，再猜再试（mcp: describe_object serves formula, autonumber and edit-denied fields as readonly: false #32530）。
• 权限与边界：HTTP 按字段的原始声明判断 readonly，但回答的其余内容仍来自遮蔽后的对象。调用者看不到表达式引用的字段时，只多知道一个布尔值「此字段是计算的」，表达式和它的输入不外露。没有新增读取。stdio 与资源只拿得到遮蔽后的对象，这一缺口另立 mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156。
• 风险与回滚：只放宽回答，不拒绝任何新输入；普通字段仍是 false，声明只读的仍是 true（有对照用例）。回滚就是 revert，不涉及数据。
• 先看：packages/runtime/src/domains/mcp.ts 的 describeObject（声明与遮蔽分两步）和两处孪生 writeNeverSetsField。
• 需要你做的：无，席位落地。
• 席位意见：落地。两轮契约复审（TIER_DEFAULT，widening 面）都 PASS；首轮的应修项 S1（字段遮蔽删掉表达式后误答 false）在 HTTP 上已修，stdio 侧缺口已立卡。CI 全绿，没有碰受管面，改动 372 行。

席位核对

• 形态: draft → main，正文写 Fixes #32530，合并后应当关卡；正文其余地方没有挨着别的 open 卡号的闭合关键词。
  • Clause-②: yes (widening)、Metadata-protocol: none。
  • Skills-docs 不欠：skill-md.ts 提到 describe_object 但不复述 readonly / defaultValue，Console 镜像不变。
  • 文件面 = 认领 6862710400。
• 前提实测: dev 在派发时的 origin/main 上实测了卡上的缺陷：手写的 autonumber 字面量、公式字段和存储表达式字段都被答成 readonly: false，而引擎会覆盖写入的值（报告 6863976414）。
• 门禁 check-runs @ 92fba691: 35 success、18 skipped、0 失败。正文修订后重跑的 PR-body guards 和 Check Changeset 由自动合并等待。
  • 本地在 92fba691 上重新推导出 66 个门禁族，--ran 对账为 66 个已计、66 个已跑、0 个 NOT MEASURED，全部 exit 0。其中 check:dual-build-cjs-loads 是在合并后的闭包构建之后跑的。pnpm lint exit 0。记录在 server-seat-7/r2026-11-13/out/32530-gates-ran-92fba691.list。
• 契约复审: 同一位复审者做了两轮。
  • 首轮 6864113097 在 819ea267 上 PASS，留一个应修项 S1：字段遮蔽会删掉可读字段上引用了不可读字段的 expression，于是该字段被答成 readonly: false，引擎却仍会计算这一列。另有 nit N1–N3。
  • 第二轮 6866437584 在 92fba691 上 PASS：
    • S1 在 HTTP 上已修，改为读声明、回答遮蔽视图，并加了 marked_up / hidden_cost 的 pin；
    • 没有新的读取，除这一个布尔值外也没有其他键外泄；
    • N2 已修；
    • 新增 nit N4（正文未更新），dev 已通过 relay issue_patch 修好，读回一致。
• 接受的偏差:
  • N1：公式谓词沿用 isVirtualSearchField，名字说的是搜索；
  • N3：引擎一侧的 pin 只测 create；
  • 两处孪生实现有意不同：stdio 与资源只持有遮蔽视图，JSDoc 和 changeset 都写明了。
• 范围外去向:
  • stdio 与资源上的表达式 readonly 缺口已立卡 mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156。
  • 卡上的 item 2，即调用者的编辑权限判定，取 (b)：只在说明文字里写明。改为 (a) 需要哪些新读取，写在 Acceptance notes 里，没有另立卡，因为 (a) 是卡上有意不取的选项。
• 落地条款: 维护者常设落地令 「按 pm-dispatch 审过的pr你可以自主落地」 (2026-10-30T14:20Z)。
  • 非受管面：check-governed-merges --pr 33150 判定 NOT governed。372 行 ≤ 3000。
  • K = 7（PRBASE 128b6571，取自 Test Core 计划的 Affected-set diff base；origin/main 47f6c939），小于 15，无需先 merge main。
  • mcp-http-tools.ts 与 runtime/src/domains/mcp.ts 与本席位的 storage + mcp: one upload link on a multiple: true file field accepts several files (same user, record, field, one use, same expiry) — ruled A #32747（PR feat(storage,mcp): one upload link takes several files on a multi-file field #33151，仍在复审）共用，本 PR 先落。
  • 没有新的语种包。